=begin pod :kind("Language") :subkind("Language") :category("reference")

=TITLE FAQ

=SUBTITLE Frequently asked questions about Raku™

=head1 General

X<|Rakudo, Raku and Perl 6 (FAQ)>
=head2 What's the difference between Raku, Rakudo and Perl 6?

Properly speaking, L<Rakudo|https://rakudo.org/> is an implementation of Raku.
It's currently the one that's being developed, but there have been other
implementations in the past and there will likely be others in the future.
Raku is the definition of the language. When talking about the current
interpreter, Rakudo and Raku can be used interchangeably.  "Perl 6" is the
name that was used for "Raku" before October 2019.

=head2 When was Raku released?

The Rakudo 2015.12 implementation version was released on December 25th 2015.

=head2 Is there a Raku version 6.0.0?

No. The first stable language specification version is v6.c
("Christmas"). Future versions of the spec may have point releases (e.g.,
v6.d.2) or major releases (e.g., v6.e).

Running C<raku -v> will display the language version your compiler
implements:

=for code :lang<shell>
$ raku -v
This is Rakudo version 2017.07 built on MoarVM version 2017.07
implementing Raku.c.

X<|v6.d (FAQ)>
=head2 When was v6.d released?

The v6.d Specification was released on
L<Diwali 2018|https://en.wikipedia.org/wiki/Diwali>,
which was November 6–7 2018, in a
convenient time zone. 6.d was enabled by default in the Rakudo compiler
release of 2018.11.

The vast majority of 6.d features were already implemented and available
in the Rakudo compiler without requiring any special pragmas, as they
did not conflict with the 6.c specification. A smaller set of features
and behaviors is available automatically if you have the C<use
v6.d> pragma at the top of the file. The rest of about 3100 new
commits to the language specification simply clarify previously
undefined behavior.

X<|Rakudo Star DMG binary installer (FAQ)>
X<|Rakudo Star MSI binary installer (FAQ)>
X<|Rakudo Star docker image (FAQ)>
X<|Rakudo Star for Linux (FAQ)>
X<|Rakudo Star for Windows (FAQ)>
X<|Rakudo Star for Mac (FAQ)>
=head2 As a Raku user, what should I install?

Mac users can use the latest Rakudo Star DMG binary installer at
L<https://rakudo.org/downloads/star>

Windows users can use the Rakudo Star MSI binary installer. You will
need Windows Git and Strawberry Perl to use zef to install library
modules.

Linux users probably want to download Rakudo Star and follow the
compilation instructions at L<https://www.raku.org/downloads/>.

There should be Linux and Mac binaries available from vendors and third
parties, although vendor versions may be outdated. Versions before
Rakudo release of 2015.12 should be avoided.

There's an official Rakudo Star docker image at
L<https://hub.docker.com/_/rakudo-star/>

X<|rakubrew (FAQ)>
X<|rakudobrew (FAQ)>
=head2 As an advanced user I want to track Rakudo development.

An option is to clone L<the repository|https://github.com/rakudo/rakudo> and
build it. This will install work in progress which is minimally-tested and
may contain severe bugs. If you're interested in contributing to the Rakudo
Raku compiler, you may find the
L<Z-Script helper tool|https://github.com/zoffixznet/z> useful.

To install the last official monthly release, check out the tag visible
at L<https://raw.githubusercontent.com/rakudo/rakudo/master/VERSION> or
set up L<a helper command|https://github.com/zoffixznet/r#table-of-contents>.

Some users choose to use L<rakubrew|https://rakubrew.org/>, which allows
quick installation of multiple versions of Rakudo in parallel.

In either case you will probably need to also install
L«C<zef>|https://modules.raku.org/dist/zef:github» and
L«C<p6doc>|https://modules.raku.org/dist/p6doc:github» from the
L<ecosystem|https://modules.raku.org/>.

=head2 Where can I find good documentation on Raku?

See L<the official documentation website|/>
(especially its L<"Language" section|/language.html>) as well as the
L<Resources page|https://raku.org/resources/>. You can also consult
this L<great cheatsheet|https://htmlpreview.github.io/?https://github.com/perl6/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.html>.

L<perl6book.com|https://perl6book.com/> contains a list of dead tree and
electronic books.

Be mindful of publication dates when reading third-party articles.
Anything published before December, 2015 likely describes a pre-release
version of Raku.

You can always
L<get help from a live human in our help chat|https://web.libera.chat/?channel=#raku>
or L<search the chat logs|https://colabti.org/irclogger/irclogger_log_search/raku>
to find previous conversations and discussions.

X<|Books>
=head2 Can I get some books about Raku?

Here are some available books, in alphabetical order:


=item L<Learning Raku|https://www.learningraku.com/>, by brian d foy

=item L<Learning to program with Raku: First Steps|https://www.amazon.com/gp/product/B07221XCVL>, by JJ Merelo

=item L<Metagenomics|https://www.gitbook.com/book/kyclark/metagenomics/details>,
by Ken Youens-Clark

=item L<Parsing with Perl 6 Regexes and Grammars|https://smile.amazon.com/dp/1484232275/>, by Moritz Lenz

=item L<Perl 6 at a Glance|https://deeptext.media/perl6-at-a-glance/>,
by Andrew Shitov

=item L<Raku Fundamentals|https://www.apress.com/gp/book/9781484261088>,
by Moritz Lenz

=item L<Perl 6 Deep Dive|https://www.packtpub.com/application-development/perl-6-deep-dive>, by Andrew Shitov

=item L<Think Perl 6: How to Think Like a Computer Scientist|https://greenteapress.com/wp/think-perl-6/>, by Laurent Rosenfeld.

A list of books published or in progress is maintained in
L<C<raku.org>|https://raku.org/resources/>.

X<|Specification (FAQ)>
=head2 What is the Raku specification?

The specification refers to the official test suite for Raku. It's called
L<C<roast>|https://github.com/Raku/roast> and is hosted on github. Any
compiler that passes the tests is deemed to implement that version of the
Raku specification.

Roast's C<master> branch corresponds to the latest development that isn't
necessarily part of any specification yet. Other branches
correspond to specific versions; for example, "6.c-errata".

So C<6.c-errata> is a released language version we don't change other than to
fix errors in tests (the "errata") whereas master is the unreleased
work-in-progress that may become the next language version. Its current state
is not necessarily prescriptive of the next language version's behavior since
new additions will be reviewed for inclusion into the release.

=head2 Is there a glossary of Raku related terms?

Yes, see L<glossary|/language/glossary>.

=head2 I'm a Perl programmer. Where is a list of differences between Perl
and Raku?

There are several I<Perl to Raku> guides in the
L<Language section of the documentation|/language.html>, most notable of which
is the L<Overview|/language/5to6-nutshell>.

X<|Ruby Quickstart (FAQ)>
=head2 I'm a Ruby programmer looking for quickstart type docs?

See the L<rb-nutshell|/language/rb-nutshell> guide.

=head1 Modules

X<|CPAN (FAQ)>X<|ecosystem>
=head2 Is there a repository of third party library modules for Raku?

Yes. As a user, the
L«C<zef> module installer|https://github.com/ugexe/zef» will
automatically install the version of a module with the highest
version number.  If you want a specific version and/or a version
from a specific author, you can also specify that with C<zef>.

As a new module author, you can use the
L<C<fez> module uploader|https://raku.land/zef:tony-o/fez>
to upload your module to the Raku ecosystem.  There are also a
number of helper modules that help you set up a skeleton of a
distribution, such as L<C<App::Mi6>|https://raku.land/cpan:SKAJI/App::Mi6>,
which will also help you with uploading once your module is
ready for distribution.

Historically, you could also upload a Raku module to CPAN by using
L<PAUSE|https://pause.perl.org/> to upload a module.  And before
that, there was a way of using Github/Gitlab to make your module
available for download.  These are now considered to not be the
best way for new module authors to start with.

X<|p6doc (FAQ)> X<|perldoc (FAQ)>
=head2 Is there a perldoc (command line documentation viewer) for Raku?

Yes, it's called C<p6doc> and is present in the ecosystem under that name. It
comes bundled in with Rakudo Star but needs to be manually installed with C<zef>
if you are using a Rakudo monthly release.

X<|Perl modules (FAQ)>
=head2 Can I use Perl modules from Raku?

Yes, with L<Inline::Perl5|https://github.com/niner/Inline-Perl5/>, which works
well with most Perl modules. It can even run Perl Catalyst and DBI.

X<|C and C++ (FAQ)>
=head2 Can I use C and C++ from Raku?

L<Nativecall|/language/nativecall> makes this
particularly easy.

=head2 Nativecall can't find C<libfoo.so> and I only have C<libfoo.so.1.2>!

In most Linux systems, shared libraries will be installed in such a way that,
 for a specific C<libfoo>, there will be a C<libfoo.so.x.y.z> real file, and
 then a set of symlinks C<libfoo.so> and C<libfoo.so.x>. for instance, C<ls
 /usr/local/lib/libxxhash.so*> returns:

=for code :lang<text>
/usr/local/lib/libxxhash.so -> libxxhash.so.0.6.5
/usr/local/lib/libxxhash.so.0 -> libxxhash.so.0.6.5
/usr/local/lib/libxxhash.so.0.6.5

In general, installing a C<libfoo-dev> or C<libfoo-devel> (depending on the
distro) in Linux will install the shared library I<and> set up those symlinks
 for you. But in some cases, you will only have, as in the question,
C<libfoo.so.1.2>.

In that case, just use the version of C<is native> that explicitly sets the
 ABI/API version, as indicated in
L<the manual|/language/nativecall#ABI/API_version>:

=for code :skip-test<snippet>
sub call-foo() is native('foo',v1.2);


=head2 Where have all the traditional UNIX library functions gone?

It's fairly easy to use L<NativeCall|/language/nativecall> to access them.

An ecosystem module L<POSIX|https://github.com/cspencer/perl6-posix> is
also available.

X<|Core standard library (FAQ)>
X<|Rakudo Star distribution and compiler-only release (FAQ)>
=head2 Does Rakudo have a core standard library?

L<Rakudo Star distribution|https://rakudo.org/downloads/> does come
with L<many useful modules|https://github.com/rakudo/star/blob/master/etc/modules.txt>.

Rakudo compiler-only release includes
L<only a couple of the most basic modules|/language/modules-core>.

Many more modules can be found in the L<ecosystem|https://modules.raku.org/>.

=head2 Is there something like C<B::Deparse>/How can I get hold of the AST?

Use C<--target=optimize> command line option to view the AST of your program,
e.g., C<raku --target=optimize -e 'say "hi"'>

The target C<optimize> gives the AST after the static optimizer does its job,
while target C<ast> gives the AST before that step. To get the full list of
available targets, run C<raku --stagestats -e "">

X<|Precompile (FAQ)>
=head2 What is precompilation?

When you load a module for the first time, Rakudo compiles it into bytecode.
Then, Rakudo both stores the compiled bytecode on disk and uses it, because
that tends to be significantly faster.

X<|Circular dependencies (FAQ)>
=head2 Can I have circular dependencies between modules?

No, you can't have circular dependencies, and you should
get a C<Circular module loading detected> error if you have them between your
modules.

Very likely you can accomplish what you are trying to do using
L<roles|/language/objects#Roles>. Instead of C<A.rakumod> depending on
C<B.rakumod> and C<B.rakumod> depending on C<A.rakumod>, you can have C<A-Role.rakumod>
and C<B-Role.rakumod> and classes in C<A.rakumod> and C<B.rakumod> implementing these
roles respectively. Then you can depend on C<A-Role.rakumod> and
C<B-Role.rakumod> without the need for the circular dependency.

One of the reasons why circular dependencies do not work in Raku is
one pass parsing. We have to know what A means when we parse B, and we
have to know what B means when we parse A, which is clearly an
infinite loop.

Note that Raku has no “1 file = 1 class” limitation, and circular
dependencies within a single compilation unit (e.g., file) are possible
through stubbing. Therefore another possible solution is to move
classes into the same compilation unit.


=head1 Common operations

=head2 String: How can I parse and get a L<number|/language/numerics> from a L<string|/language/type/Str>?

Use the L<+ prefix|/language/operators#prefix_+>:

=begin code :ok-test<dd>
say "42.123456789123456789";  # OUTPUT: «42.123456789123456789␤»
say +"42.4e-2";               # OUTPUT: «0.424␤»
=end code

This example of L<contextualization|/language/contexts> can numify any string you could enter as a L<literal number|/language/syntax#Number_literals>.
L<val|/routine/val> routine converts it to L<allomorph|/language/glossary#Allomorph>.
L<unival|/routine/unival> routine converts one unicode codepoint.

=head2 String: How can I check if a string contains a substring and if so, how can I get indices of matches?

Use L<.contains|/type/Str#method_contains> or L<.indices|/type/Str#method_indices>:

=begin code
"az and az and az again".contains("az"); # OUTPUT: «True␤»
"az and az and az again".indices("az");  # OUTPUT: «(0 7 14)␤»
=end code

=head2 String: How can I get the hexadecimal representation of a string?

To get a hexadecimal list of each byte of a string (i.e. hex encoder),
first convert the string to a L<Blob|/type/Blob> with L<.encode|/routine/encode>.

=begin code
say "I ❤ 🦋".encode>>.base(16);  # OUTPUT: «(49 20 E2 9D A4 20 F0 9F A6 8B)␤»
=end code

Note that L<.gist|/routine/gist> or L<.raku|/routine/raku> methods can be useful for variable introspection:

=begin code
say "I ❤ 🦋".encode.raku;  # OUTPUT: «utf8.new(73,32,226,157,164,32,240,159,166,139)␤»
say "I ❤ 🦋".encode.gist;  # OUTPUT: «utf8:0x<49 20 E2 9D A4 20 F0 9F A6 8B>␤»
=end code

=head2 String: How can I remove from a string some characters by index?

Use L<.comb|/routine/comb> to transform it to a L<Seq|/type/Seq>, then the L<(-) infix|/language/operators#infix_-> to remove the unwanted indices:

=begin code
say '0123456789'.comb[(^* (-) (1..3, 8).flat).keys.sort].join;  # OUTPUT: «045679␤»
=end code

If the string is large, L<.comb|/routine/comb> can take time. In which case, L<.substr-rw|/routine/substr-rw> is faster:

=begin code
multi postcircumfix:<[- ]> (Str:D $str is copy, +@indices) {
    for @indices.reverse {
        when Int   { $str.substr-rw($_,1) = '' }
        when Range { $str.substr-rw($_  ) = '' }
    }
    return $str;
}

say '0123456789'[- 1..3, 8 ];  # OUTPUT: «045679␤»
=end code

=head2 String: How can I split a string in equal parts?

L<.comb|/routine/comb> is accepting an optional L<Int|/type/Int>:

=begin code
.say for 'abcdefghijklmnopqrstuvwxyz'.comb: 8;  # OUTPUT: «abcdefgh␤ijklmnop␤qrstuvwx␤yz»
=end code

=head1 Language features

X<|Data::Dumper (FAQ)>
=head2 How can I dump Raku data structures
(like Perl Data::Dumper and similar)?

Typical options are to use the L<say|/routine/say> routine that uses
the L<gist|/routine/gist> method which gives the "gist" of the object being
dumped. More detailed output can be obtained by calling the
L<perl|/routine/perl> method (soon to be deprecated in favor of C<$obj.raku>,
available since the Rakudo 2019.11 release) that typically returns an object's
representation in L<EVAL|/routine/EVAL>-able code.

If you're using the L<rakudo|https://rakudo.org> implementation, you can use
the L«rakudo-specific C<dd> routine|/programs/01-debugging#Dumper_function_(dd)»
for dumping, whose output is similar to L<raku|/routine/raku>, but
with more information.

Examples:

=begin code :ok-test<dd>
my $foo = %( foo => 'bar' );
say $foo.raku;   # OUTPUT: «${:foo("bar")}␤»
say $foo;        # OUTPUT: «{foo => bar}␤»

# non-standard routine available in rakudo implementation:
dd $foo;         # OUTPUT: «Hash $foo = ${:foo("bar")}␤»
=end code

There are also L<several ecosystem modules|https://modules.raku.org/s/dump>
that provide more control over how data structures are dumped, including
support for colored output.

=head2 How can I get command line history in the Raku prompt (REPL)?

Install L<Linenoise|https://github.com/hoelzro/p6-linenoise/> from the
ecosystem.

An alternative for UNIX-like systems is to install C<rlwrap>. This can
be done on Debian-ish systems by running:

=for code :lang<shell>
sudo apt-get install rlwrap

=head2 Why is the Rakudo compiler so apologetic?

If SORRY! is present in the output, the error is a compile time error.
Otherwise, it's a runtime error.

Example:

=begin code :skip-test<compile time error>
sub foo( Int $a, Int $b ) {...}
foo(1)     # ===SORRY!=== Error while compiling ...
=end code

=for code
say 1/0;   # Attempt to divide 1 by zero using div

=head2 What is C<(Any)>?

L«C<Any>|/type/Any» is a top level class most objects inherit from.
The C<Any> type object is
L<the default value|/type/Attribute#Trait_is_default> on variables and
parameters without an explicit type constraint, which means you'll
likely see C<(Any)> printed when you output a L<gist|/routine/gist> of
a variable without any value by using, for instance, the
L«C<say> routine|/routine/say»:

=begin code
my $foo;
say $foo; # OUTPUT: «(Any)␤»

my Int $baz;
say $baz; # OUTPUT: «(Int)␤»

my $bar = 70;
say $bar; # OUTPUT: «70␤»
=end code

To test whether a variable has any defined values, see
L<DEFINITE|/language/classtut#index-entry-.DEFINITE> and L<defined|/routine/defined>
routines. Several other constructs exist that test for definiteness, such as
L«C<with>, C<orwith>, and C<without>|/syntax/with orwith without»
statements, L«C<//>|/routine/$SOLIDUS$SOLIDUS», L<andthen|/routine/andthen>,
L<notandthen|/routine/notandthen>, and
L<orelse|/routine/orelse> operators, as well as
L<type constraint smileys|/type/Signature#Constraining_argument_definiteness>.

=head2 What is C<so>?

C<so> is a loose precedence operator that coerces to L<Bool|/type/Bool>.

It has the same semantics as the C<?> prefix operator, just like
C<and> is the low-precedence version of C<&&>.

Example:

=for code
say so 1|2 == 2;    # OUTPUT: «True␤»

In this example, the result of the comparison (which is a
L<Junction|/type/Junction>), is converted to Bool before being printed.

=head2 What are those C<:D> and C<:U> things in signatures?

In Raku, classes and other types are objects and pass type checks
of their own type.

For example, if you declare a variable

=for code
my Int $x = 42;

then not only can you assign integers (that is, instances of class Int) to it,
but the C<Int> type object itself:

=begin code :preamble<my Int $x>
$x = Int
=end code

If you want to exclude type objects, you can append the C<:D> type smiley,
which stands for "definite":

=begin code
my Int:D $x = 42;
$x = Int;

# dies with:
# Type check failed in assignment to $x;
# expected Int:D but got Int
=end code

Likewise, C<:U> constrains to undefined values, that is, type objects.

To explicitly allow either type objects or instances, you can use C<:_>.

=head2 What is the C«-->» thing in the signature?

L«-->|/type/Signature#Constraining_return_types» is a return constraint, either
a type or a definite value.

Example of a type constraint:

=begin code
sub divide-to-int( Int $a, Int $b --> Int ) {
        return ($a / $b).narrow;
}

divide-to-int(3, 2)
# Type check failed for return value; expected Int but got Rat
=end code

Example of a definite return value:

=begin code
sub discard-random-number( --> 42 ) { rand }
say discard-random-number;
# OUTPUT: «42␤»
=end code

In this case, the final value is thrown away because the return value is
already specified in the signature.

X<|Junction (FAQ)>
=head2 How can I extract the values from a Junction?

If you want to extract the values (eigenstates) from a
L<Junction|/type/Junction>, you are probably doing something wrong and
should be using a L<Set|/type/Set> instead.

Junctions are meant as matchers, not for doing algebra with them.

If you want to do it anyway, you can abuse autothreading for that:

=begin code
sub eigenstates(Mu $j) {
    my @states;
    -> Any $s { @states.push: $s }.($j);
    @states;
}

say eigenstates(1|2|3).join(', ');
# prints 1, 2, 3 or a permutation thereof
=end code

=head2 If Str is immutable, how does C<s///> work? If Int is immutable,
how does C<$i++> work?

In Raku, values of many basic types are immutable, but the variables holding
them are not. The C<s///> operator works on a variable, into which it puts a
newly created string object. Likewise, C<$i++> works on the C<$i> variable, not
just on the value in it.

Knowing this, you would not try to change a literal string (e.g. like
C<'hello' ~~ s/h/H/;>), but you might accidentally do something equivalent
using C<map> as follows.

=begin code
my @foo = <hello world>.map: { s/h/H/ };

# dies with
# Cannot modify an immutable Str (hello)

my @bar = <hello world>».subst-mutate: 'h', 'H';

# dies with
# Cannot resolve caller subst-mutate(Str: Str, Str);
# the following candidates match the type but require
# mutable arguments: ...
=end code

Instead of modifying the original value in place, use a routine or operator
that returns a new value:

=begin code
my @foo = <hello world>.map: { S/h/H/ };  # ['Hello','world']
my @bar = <hello world>».subst: 'h', 'H'; # ['Hello','world']
=end code

See the documentation on L<containers|/language/containers> for more
information.

=head2 What's up with array references and automatic dereferencing?
Do I need the C<@> sigil?

In Raku, nearly everything is a reference, so talking about taking
references doesn't make much sense. Scalar variables can also contain
arrays directly:

=begin code
my @a = 1, 2, 3;
say @a;                 # OUTPUT: «[1 2 3]␤»
say @a.^name;           # OUTPUT: «Array␤»

my $scalar = @a;
say $scalar;            # OUTPUT: «[1 2 3]␤»
say $scalar.^name;      # OUTPUT: «Array␤»
=end code

The big difference is that arrays inside a scalar act as one value in list
context, whereas arrays will be happily iterated over.

=begin code
my @a = 1, 2, 3;
my $s = @a;

for @a { ... }          # loop body executed 3 times
for $s { ... }          # loop body executed only once

my @flat = flat @a, @a;
say @flat.elems;            # OUTPUT: «6␤»

my @nested = flat $s, $s;
say @nested.elems;          # OUTPUT: «2␤»
=end code

You can force list context with C<@( ... )> or by calling the
C<.list> method on an expression, and item context with
C<$( ... )> or by calling the C<.item> method on an expression.

See the L«I<Perl 6: Sigils, Variables, and Containers>|https://perl6advent.wordpress.com/2017/12/02/» article to learn more.

X<|Sigils (FAQ)>
=head2 Why sigils? Couldn't you do without them?

There are several reasons:

=item they make it easy to interpolate variables into strings

=item they form micro-namespaces for different variables and twigils, thus
avoiding name clashes

=item they allow easy single/plural distinction

=item they work like natural languages that use mandatory noun markers, so
our brains are built to handle it

=item they aren't mandatory, since you can declare sigilless names
(if you don't mind the ambiguity)

=head2 "Type Str does not support associative indexing."

You likely tried to mix string interpolation and key characters, like HTML tags:

=begin code
my $foo = "abc";
say "$foo<html-tag>";
=end code

Raku thinks C<$foo> is a Hash and C«<html-tag>» is a string literal
hash key. Use a closure to help it to understand you.

=begin code
my $foo = "abc";
say "{$foo}<html-tag>";
=end code

X<|Coroutine (FAQ)>
=head2 Does Raku have coroutines? What about C<yield>?

Raku has no C<yield> statement like Python does, but it does offer similar
functionality through lazy lists. There are two popular ways to write
routines that return lazy lists:

=begin code :preamble<sub have_data {};sub some_data {};>
# first method, gather/take
my @values = gather while have_data() {
    # do some computations
    take some_data();
    # do more computations
}

# second method, use .map or similar method
# on a lazy list
my @squares = (1..*).map(-> \x { x² });
=end code

=head2 Why can't I initialize private attributes from the new method,
and how can I fix this?

The C<say> statement in the following code sample

=begin code
class A {
    has $!x;
    method show-x {
        return $!x;
    }
}
say A.new(x => 5).show-x;
=end code

does not print 5. Private attributes are I<private>, which means invisible to
the outside world. If the default constructor could initialize them, they would
leak into the public API. Thus, in this particular code sample the attribute
C<$!x> isn't initialized during object construction by the default
constructor.

If you still want to initialize private attributes with the default constructor,
you can add a C<submethod BUILD> to achieve such task:

=begin code
class B {
    has $!x;
    submethod BUILD(:$!x) { }
    method show-x {
        return $!x;
    }
}
say B.new(x => 5).show-x;
=end code

C<BUILD> is called by the default constructor (indirectly, see
L<Object Construction|/language/objects#Object_construction>
for more details) with all the named arguments that the user passes to the
constructor. C<:$!x> is a named parameter with name C<x>, and when called
with a named argument of name C<x>, its value is bound to the attribute C<$!x>.

However, you shouldn't do that. If the attribute is declared as private,
then it shouldn't be exposed to the environment outside the class (e.g.,
during object construction). On the other hand, if the attribute is public,
there is no downside to declaring it that way with C<$.x> since the external
view is read-only by default, and you can still access it internally with C<$!x>.

=head2 How and why do C<say>, C<put> and C<print> differ?

The most obvious difference is that C<say> and C<put> append
a newline at the end of the output, and C<print> does not.

But there's another difference: C<print> and C<put> convert their
arguments to a string by calling the C<Str> method on each item
passed to them while C<say> uses the C<gist> method. The C<gist> method,
which you can also create for your own classes, is intended to create a
C<Str> for human interpretation. So it is free to leave out information
about the object deemed unimportant to understanding the essence of the object.

Or phrased differently, C<$obj.Str> gives a string representation,
C<$obj.gist> provides a short summary of that object suitable for
fast recognition by a human, and C<$obj.raku> gives a Raku-ish
representation from which the object could be re-created.

For example, when the C<Str> method is invoked on a type object, also known
as an "undefined value", the type is stringified to an empty string
and a C<warn>ing is thrown. On the other hand, the C<gist> method returns the
name of the type between parentheses (to indicate there's nothing in that
value except the type).

=begin code
my Date $x;     # $x now contains the Date type object
print $x;       # empty string plus warning
say $x;         # OUTPUT: «(Date)␤»
=end code

If you'd like to show a debugging version of an object, it is probably better
to use the L«rakudo-specific C<dd> routine|/programs/01-debugging#Dumper_function_(dd)».
It essentially does a C<$obj.raku> and shows that on STDERR rather than
STDOUT, so it won't interfere with any "normal" output of your program.

In short, C<say> is optimized for casual human interpretation, C<dd> is optimized
for casual debugging output and C<print> and C<put> are more generally suitable
for producing output.

C<put> is thus a hybrid of C<print> and C<say>; like C<print>, it calls the
C<Str> method on the object. And like C<say>, it adds a newline at the end
of the output.

=head2 What's the difference between C<token> and C<rule> ?

C<regex>, C<token> and C<rule> introduce regexes, but with
slightly different semantics.

C<token> implies the C<:ratchet> or C<:r> modifier, which prevents the
rule from backtracking.

C<rule> implies both the C<:ratchet> and C<:sigspace> (short C<:s>)
modifier, which means a rule doesn't backtrace, and it treats
whitespace in the text of the regex as C«<.ws>» calls (i.e.,
matches whitespace, which is optional except between two word
characters). Whitespace at the start of the regex and at the start
of each branch of an alternation is ignored.

C<regex> declares a plain regex without any implied modifiers.

=head2 What's the difference between C<die> and C<fail>?

C<die> throws an exception.

C<fail> returns a C<Failure> object. (If the caller has declared C<use fatal;>
in the calling lexical scope, C<fail> throws an exception instead of
returning it.)

A C<Failure> is an "unthrown" or "lazy" exception. It's an object that contains
the exception, and throws the exception if you try to use the C<Failure>
as an ordinary object or ignore it in sink context.

A C<Failure> returns C<False> from a C<defined> check, and you can extract
the exception with the C<exception> method.

=head2 What's the difference between C<Pointer> and C<OpaquePointer>?

C<OpaquePointer> is deprecated and has been replaced with C<Pointer>.

=head2 You can have colonpairs in identifiers. What's the justification?

L<Identifiers can include colon pairs, which become part of their name|/language/syntax#Identifiers>.
According to
L<Larry Wall's answer to the issue|https://github.com/Raku/doc/issues/1753#issuecomment-362875676>,
I<We
already had the colon pair mechanism available, so it was a no-brainer to use
that to extend any name that needs to be able to quote uniquefying but
non-standard characters (or other information with a unique stringification to
such characters)>.

=head2 How do most people enter unicode characters?

It depends on the operating system, windowing environment and/or editors. L<This
page on entering Unicode characters|/language/unicode_entry> specifies how it is
done in the most popular operating systems and editors.

X<|Raku Implementation (FAQ)>
=head1 Raku implementation

=head2 What Raku implementations are available?

Currently the best developed is Rakudo (using multiple Virtual Machine
backends). Historic implementations include Niecza (.NET) and Pugs (Haskell).
Others are listed at L<Raku Compilers|https://www.raku.org/compilers/>

=head2 What language is Rakudo written in?

A short answer is that Rakudo is written almost entirely in Raku. A more
detailed answer is that Rakudo is written in a mixture of Raku and NQP ("Not
Quite Perl"). NQP is a lightweight Raku-like environment for virtual
machines; it's designed to be a high-level way to create compilers and
libraries for virtual machines (such as MoarVM and JVM) using Raku syntax.

X<|NQP (FAQ)>
=head2 What language is NQP written in?

NQP is a mixture of (1) NQP code, (2) whatever language the underlying virtual
machine is using, (3) some third-party C and Java libraries, and (4) some
bootstrapping files created by earlier runs of the build process.

=head2 Is Raku Lisp?

=for code
(not (not Nil))

=head2 Can I compile my script to a standalone executable?

Tools like
L«C<App::InstallerMaker::WiX>|https://modules.raku.org/dist/App::InstallerMaker::WiX»
allow you to create an installer that will package the compiler and your script.
However, the currently available compilers do not support creating a standalone
executable yet.

If you wish to help out, the I<Rakudo> compiler on I<MoarVM> backend has
L<https://github.com/MoarVM/MoarVM/issues/875> issue opened as a place to
discuss this problem.

X<|Raku Distribution (FAQ)>
=head1 Raku distribution

X<|Rakudo Star release cycle (FAQ)>
=head2 When will the next version of Rakudo Star be released?

A Rakudo Star release is typically produced quarterly, with release
announcements L<posted on rakudo.org|https://rakudo.org/news>.

=head1 Metaquestions and advocacy

=head2 Why was Raku originally called Perl 6?

… As opposed to some other name that didn't imply all the things
that the higher number might indicate on other languages.

The short answer is that it was Larry's choice under
L<Rule 1|https://perldoc.perl.org/5.12.4/perlhack.html#DESCRIPTION>.

The community considers Perl and Raku sister languages - they have
a lot in common, address many of the same problem spaces, but Raku is not
intended to replace Perl. In fact, both languages interoperate with
each other.

=head2 When will Raku be ready? Is it ready now?

Readiness of programming languages and their compilers is not a binary
decision. As the language and the implementations evolve, they
grow steadily more usable. Depending on your needs,
Raku and its compilers may or may not be ready for you.

That said, version 6.c (Christmas 2015) is the first official release of Raku
as a language, along with a validation suite and a compiler that passes it.

=head2 Why should I learn Raku? What's so great about it?

Raku unifies many great ideas that aren't usually found in other programming
languages. While several other languages offer some of these features, none of
them offer all of them.

=item Raku offers procedural, object-oriented AND functional programming
methodologies.

=item Easy to use consistent syntax, using invariable sigils for data-structures.

=item Full grapheme based Unicode support, including Annex #29.

=item Clean, more readable regular expressions; taken to the next level of
usability, with a lot more functionality. Named regular expressions improve
ease of use.

=item Junctions allowing easy checking of multiple possibilities;
e.g., C<$a == 1|3|42> (Is C<$a> equal to 1 or 3 or 42?).

=item Dynamic variables provide a lexically scoped alternative to global
variables.

=item Emphasis on composability and lexical scoping to prevent
“action at a distance”; e.g., imports are always lexically scoped.

=item Easy to understand consistent scoping rules and closures.

=item Powerful object orientation, with classes and roles (everything can be
seen as an object). Inheritance. Subtyping. Code-reuse.

=item Introspection into objects and metaobjects (turtles all the way down).

=item MetaObject Protocol allowing for metaprogramming without needing to
generate or parse code.

=item Subroutine and method signatures for easy unpacking of positional and
named parameters.

=item Multi-dispatch for identically named subroutines/methods with different
signatures, based on arity, types and optional additional code.

=item Compile time error reporting on unknown subroutines or impossible dispatch.

=item Optional gradual type-checking at no additional runtime cost. With
optional type annotations.

=item Advanced error reporting based on introspection of the compiler/runtime
state. This means more useful, more precise error messages.

=item Phasers (like C<BEGIN> / C<END>) allow code to be executed at scope
entry / exit, loop first / last / next and many more special contexts.

=item High level concurrency model, both for implicit as well as explicit
multi-processing, which goes way beyond primitive threads and locks. Raku's
concurrency offers a rich set of (composable) tools.

=item Multiple-core computers are getting used more and more, and with Raku
these can be used thanks to parallelism, both implicit (e.g., with the C«>>».
method) and explicit ( C<start { code }> ). This is important, because Moore's
Law is ending.

=item Structured language support is provided to enable programming for
asynchronous execution of code.

=item Supplies allow code to be executed when something happens (like a timer,
or a signal, or a filesystem event).

=item C<react> / C<whenever> / C<supply> keywords allows easy construction of
interactive, event driven applications.

=item Lazy evaluation when possible, eager evaluation when wanted or necessary.
This means, for example, lazy lists, and even infinite lazy lists, like the
Fibonacci sequence, or all prime numbers.

=item Native data types for faster, closer-to-the-metal, processing.

=item Interfacing to external libraries in C and C++ is fairly easy with
L<NativeCall|/language/nativecall>.

=item Interfacing with Perl (CPAN) and Python modules is fairly easy with
L<Inline::Perl5|https://modules.raku.org/dist/Inline::Perl5:cpan:NINE> and
L<Inline::Python|https://modules.raku.org/dist/Inline::Python>

=item Can have multiple versions of a module installed and loaded
simultaneously.

=item System administration simplified due to simpler update and upgrade policies.

=item Simple numeric computation without precision loss because of
L<Rat|https://docs.raku.org/type/Rat>s (rational numbers).

=item Extensible grammars for parsing data or code (which Raku uses to parse
itself).

=item Raku is a very mutable language (define your own functions, operators,
traits and data-types, which modify the parser for you).

=item Large selection of data-types, plus the possibility to create your own
types.

=item Multi-dimensional shaped or native arrays with proper bounds checking.

=item Execute code at any time during parsing of a grammar, or when a certain
match occurred.

=item Adding a custom operator or adding a trait is as simple as writing a
subroutine.

=item Automatic generation of hyper-operators on any operator (system or custom
added).

=item Runs on a variety of back-ends. Currently MoarVM and JVM, JavaScript in
development, more may follow.

=item Runtime optimization of hot code paths during execution (JIT).

=item Runs on small (e.g., Raspberry Pi) and large multi-processor hardware.

=item Garbage collection based: no timely destruction, so no reference-counting
necessary. Use phasers for timely actions.

=item Methods can be mixed into any instantiated object at runtime; e.g., to
allow adding out-of-band data.

=item Easy command-line interface accessible by C<MAIN> subroutine with multiple
dispatch and automated usage message generation.

=item Fewer lines of code allow for more compact program creation.
Huffman-coding of names allows for better readability.

=item Lazy lists defined with a simple iterator interface, which any class can
supply by minimally supplying a single method.

=item Ability to use hyphens and other non-alphanumeric ASCII
characters as well as certain Unicode characters in identifiers. (Using
hyphens instead of underscores in test is commonly called "kebab case"
among its users. See also "camel case" and "snake case":
L<https://en.wikipedia.org/wiki/Letter_case#Special_case_styles>.)

=item Raku's mottos remain the same as they have been for Perl all along:
“Perl is different. In a nutshell, Perl is designed to make the easy jobs easy,
without making the hard jobs impossible.” and “There Is More Than One Way To Do
It”. Now with even more -Ofun added.

=head2 Is Raku fast enough for me?

That depends on what you are doing. Rakudo has been developed with the
philosophy of "make it work right then make it work fast." It's fast for some
things already but needs work for others. Since Raku provides lots of clues
to the JIT that other dynamic languages don't, we think we'll have a lot of
headroom for performance improvements.

The following crude benchmarks, with all the usual caveats about such things,
show that Raku can be faster than Perl for similar tasks if the big weaponry
is included, that is, if Raku features are used to its full extent; at the
same time, Perl can be faster if only the bare bones are included. Similar
situations can be observed when comparing Raku to other languages.

Try it on your system. You may be pleasantly surprised!

Examples:

=begin code :solo
# Raku version
class Foo { has $.i is rw };

for 1..1_000_000 -> $i {
    my $obj = Foo.new;
    $obj.i = $i;
}
=end code

=begin code :lang<perl>
# Perl version
package Foo;
use Moose;

has i => (is => 'rw');

__PACKAGE__->meta->make_immutable;

for my $i (1..1_000_000) {
    my $obj = Foo->new;
    $obj->i($i);
}

1;

# Another Perl version that offers bare-bones set of features
# compared to Moose/Raku's version but those are not needed in this
# specific, simple program anyway.
package Foo;
use Mojo::Base -base;

has 'i';

for my $i (1..1_000_000) {
    my $obj = Foo->new;
    $obj->i($i);
}

1;
=end code

You might want to use this program for comparing performance, too. It works
under both languages, as long as C<perl -Mbigint> is used for invocation for
Perl.

=begin code
my ($prev, $current) = (1, 0);

for (0..100_000) {
    ($prev, $current) = ($current, $prev + $current);
}
print $current;
=end code

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
